The terminology used in this chapter is as follows:
o “Developer” refers to the application developer.
o “User” means the end user of the application.
o “User methods” are methods designed by the developer.
o “User window” is a window created by the developer, in contrast to a Prograph window.
o An instance of a class “myClass” or of one of its subclasses is denoted «myClass». This notation is also used to mean a specific instance in some contexts: for example, in the description of the attributes of class Button, «Button» denotes the button whose attributes are being described. Specific instances that are not clear from context are further explained, for example «Point of click».
o Other data types are sometimes informally designated as <datatype>, as in <EventRecord of click>.
t An Overview *167*
One of the most complex tasks in producing software for sophisticated graphics-based computers is the design and programming of the interface, which includes interaction by means of menus and windows rather than simple line-oriented input and output.
The interface development facilities of Prograph are an extension of the environment provided by the editor/interpreter and follow the same design principles. That is, the design of the application is integrated with its testing in a complete top-down fashion.
In Prograph, an application is an instance of the system class Application; that instance in turn refers to instances of other system classes, such as Menu and Window. The application recognized by the system is the value of the class attribute current of class Application. We will refer to this instance as the current application.
Choosing Run from the Exec menu activates the current application by setting its active? attribute to TRUE, causing the windows and menus on the so-called “active lists” of the current application to be displayed, and starting the Application Manager. Conversely, setting active? of an active application to FALSE hides its windows and menus and stops the Application Manager. Among other ways, this can be accomplished by choosing Stop Running or Edit Application from the Exec menu if the Prograph editor menu bar is active.
The Application Manager intercepts all events, dispatching them to the application or to the editor/interpreter as appropriate. Events dispatched to the application can trigger the execution of user methods that implement the behavior of the application. As described in chapter 3, “The Interpreter Environment,” execution and editing of these methods can proceed in parallel. During this process, both user windows and Prograph windows can be visible at the same time, the top window generally determining the context—that is, whether the system is currently in the application state, displaying application menus, or in the editor/interpreter state, displaying Prograph menus. By selecting Switch Context from the Apple menu, the developer can force the context to be changed, regardless of the top window. Simultaneous editing and executing is particularly important in developing an application, since the effects of editing can be immediately observed on the application interface.
Physical and visual effects on an application can be produced in a number of ways.
o Some system attributes can be set. For example, setting the active? attribute of a «Window» to FALSE by using a Set operation removes this instance from the list of active windows of the current application. This, in turn, removes the window from the screen.
o Certain primitives can be called. For instance, the primitive drag-rect tracks the cursor with an outline of a rectangle in a «Canvas» .
o A Mac Method can be invoked to execute a toolbox procedure. The Mac Method PtInRect for example, given a point and a rectangle, returns TRUE if the point is within the rectangle.
t Application Manager *169*
Most system classes have instance attributes for specifying the names of user methods to be called in response to certain events dispatched to the application: such attributes are called event method attributes. For example, many Window Item subclasses have an attribute click method that names the method to call when a click is detected in a «Window Item». If an event method attribute doesn’t specify a method (that is, its value is the empty string), no method is called when the corresponding event occurs.
If the value of an event method attribute is a nonempty string that does not name an existing method, then, when the corresponding event is detected, a dialog is displayed asking the developer whether or not the method should be created. This is analogous to the situation that arises when an attempt is made to execute an operation with no corresponding method (see chapter 3, “The Interpreter Environment”).
Instances of certain system classes can appear on-screen, namely «Window»s, «Menu»s, «Window Item»s and «Menu Item»s. The instances that are displayed when an application is running are kept in various lists, detailed below, and are displayed in the order of their occurrence in these lists: «Window»s and «Window Item»s from front to back, «Menu»s from left to right in the menu bar, and «Menu Item»s from top to bottom.
The values of the attributes windows and menus of an «Application» are lists of «Window»s and «Menu»s respectively, called the active windows and menus of «Application». When an application is activated, the attribute active? of each of its active windows and menus is set to TRUE, causing them to be displayed.
The item list attribute of a «Window» (or «Menu») contains a list of «Window Item»s (or «Menu Item»s), which are displayed when the «Window» (or «Menu») is displayed.
When the application is running, pressing the Shift, Option, and Command keys while single-clicking on a «Window Item» that has a click method (that is, all «Window Item»s except for instances of Text or its subclasses) opens an editing window on the first case of the method named in the click method attribute of the «Window Item». If the name does not correspond to an existing method, a dialog is displayed asking the developer whether or not to create the method.
Similarly, pressing the Shift, Option, and Command keys while selecting a «Menu Item» opens the method named in the event method attribute method, or displays a dialog as explained in the preceding paragraph.
t System Class Methods *170*
A number of methods are shipped with the System Classes in Prograph Classic. Some of these supply basic functionality, such as Quit, Cut, Copy, Paste and Clear in class Menu. Others have to do with handling events. All these methods may be examined and modified (or overridden) by the user.
NOTE: The following convention has been adopted for names of System Classes and of System Class methods supplied by Prograph International: each word in the name begins with a capital letter. An example is the Mouse Down method in class Application. Keeping this convention in mind should reduce the likelihood of name conflicts (for example, you may want to have your method names all be lower-case).
Application *171*
Notify
Prograph passes all events to this method. Notify has one case for each type of event: null event, mouse down, key, update, activate, Apple Event, and suspend/resume.
null event Calls /Idle of the front window.
mouse down Calls Window/Mouse Down if the mouse was clicked in a
window, or Application/Mouse Down if the mouse was
clicked in the menu bar or the desktop.
key Calls Application/Menu Click for command keys, and calls
/Key of the front window otherwise.
update Figures out which window is to be updated and calls its /Update
method.
activate Figures out which window is to be activated (or deactivated) and
calls its /Activate method.
Apple Event Calls one of the Application’s aevent methods.
suspend/resume Activates or deactivates the front window by calling its /Activate
method.
Mouse Down *171*
Handles mouse down events in the menu bar and the desktop. Called from Application/Notify.
Menu Click *171*
Called when a pull-down menu item is selected or a menu key equivalent is pressed. The menu item’s click method is called, or if the About… menu item in the Apple menu is selected, the Application’s About method is called. If a desk accessory is selected in the Apple menu, the desk accessary is opened. Called from Application/Notify and Application/Mouse Down.
Front Window *172*
Returns the front window, or NULL if there is no front window or if the front window does not belong to the Application.
Update Menus *172*
Called when the user clicks on the menu bar or types a Command key. Modify this method to keep your menus up to date. Called from Application/Notify and Application/Mouse Down.
About *172*
Empty About… method. Modify this method to show your “About” dialog.
Menu
Quit *172*
Quits the current application. Calls /Close of all window items in all open windows.
Cut, Copy, Paste, & Clear *172*
Perform editing operations on selected text items.
Window
Activate *172*
Hilites the window’s items and calls the window’s activate method. Called by Application/Notify
Update *172*
Redraws the window’s item list. Called by Application/Notify.
Idle *173*
Calls sc-show-balloon to handle Balloon Help for the window; calls /Idle of the window’s selected item; then calls the window’s idle method. Called by Application/Notify.
Key *173*
If the key is a tab, calls /Tab To Item of the window item to be tabbed to. If the key is enter or return, calls the click method of the window’s default button. Otherwise, calls /Key of the window’s selected item. The window’s key method is called only when the key event is not otherwise processed. Called by Application/Notify.
Mouse Down *173*
Handles mouse down events in the window’s close box, grow box, zoom box, title bar and content. Calls the window’s /Close method when the close box is clicked. Called by Application/Notify.
Close *173*
Closes a window and calls /Close of the window’s items. This is the prescribed way of closing windows.
Open *173*
Opens a window and calls /Open of the window’s items. This is the prescribed way of opening windows.
Bring To Front *173*
Brings a window to the front.
Wind Draw Prep *173*
Prepares a window for drawing.
Window Item
Mouse Down *174*
Processes mouse down events in the window item, and then calls the item’s click method if it has one. Called by Window/Mouse Down.
Idle *174*
Flashes the caret in the selected item and changes the cursor to the I-beam if it’s over an «Edit Text» item, or to the the arrow otherwise.
Update *174*
Redraws the window item. Called by Window/Update.
Hilite *174*
Hilites or unHilites the window item temporarily. Called by Window/Activate
Open *174*
Does nothing. This method is provided for subclasses of Window Item which must be informed when their owning window is opened. Called from Window/Open.
Close *174*
Does nothing. This method is provided for subclasses of Window Item which must be informed when their owning window is closed. Called from Window/Close and Application/Quit.
Bounds *174*
Returns the bounding rectangle of the window item in window coordinates.
Canvas
Update *175*
Draws the scroll bars and border of the canvas and calls the canvas’ draw method. Overrides Window Item/Update.
Scroll List
Mouse Down *175*
Selects the Scroll List item when a mouse down occurs in it. Overrides Window Item/Mouse Down.
Tab To Item *175*
Selects the Scroll List item. Called by Window/Key.
Key *175*
Arrow keys change the selection. Other keys are ignored. Called by Window/Key.
Edit Text
Mouse Down *175*
Selects the Edit Text item when a mouse down occurs in it. Overrides Window Item/Mouse Down.
Tab To Item *175*
Selects the Edit Text item and selects all of the text in the item. Called by Window/Key.
Key *175*
Arrow keys move the caret, the delete key deletes characters, and other keys are inserted into the item’s text. Called by Window/Key.
t System Class Specifications *176*
The interface of a Macintosh application consists of windows and menus. The Prograph Application Builder facilitates the building of such interfaces. It consists of a set of System classes defining the necessary interface elements, and a set of interactive, graphical editors for editing instances of system classes. The icons for System classes are distinguished from those for user-defined classes.
The System classes are described in this chapter, while the interactive graphical editors are described in chapter 4, “Application Builder.”
 
Key *177*
Symbol Description
 
a System class
  a System class attribute
  an inherited System class attribute
  a System instance attribute
  an inherited System instance attribute
NOTE:
o The System classes are described in alphabetical order.
o System attributes are supplied with default values, some of which cannot be changed.
o “Not settable” means that the attribute value cannot be set at runtime or in a Value window.
o “Not settable on default” means that the default value of the attribute cannot be set.
o An instance of a class is “active” if its instance attribute active? has the value TRUE.
